<script type="text/html" data-help-name="ping">
    <p>Pings a machine and returns the trip time in mS as <code>msg.payload</code>.</p>
    <h3>Output</h3>
    <dl class="message-properties">
        <dt>payload <span class="property-type">number</span></dt>
        <dd> the trip time in mS, or boolean <i>false</i> if no response.</dd>
        <dt>topic <span class="property-type">string</span></dt>
        <dd> the target host or ip address.</dd>
        <dt>[ping] <span class="property-type">object</span></dt>
        <dd> an object containing <code>host</code> and any other properties sent in the array object.<br>
            <b>Note</b>: This object is only appended when using triggered mode and an array for input payload. It is
            intended for advanced users and permits scenarios where you need additional properties to be tagged into your result for use downstream.</dd>
    </dl>
    <h3>Details</h3>
    <p>Returns <b>false</b> if no response received, or if the host is unresolveable.</p>
    <p>Default ping is every 20 seconds but can be configured.</p>

    <h4>Protocol...</h4>
    <ul>
        <li><b>Automatic</b><br>
            <P>Will use any Protocol, IPv4 or IPv6, to reach host; based on your operating system network settings</P>
        </li>
        <li><b>IPv4</b><br>
            <P>Forces use of IPv4 to reach host. Will fail if no route availibe</P>
        </li>
        <li><b>IPv6</b><br>
            <P>Forces use of IPv6 to reach host. Will fail if no route availibe</P>
        </li>
    </ul>

    <h4>Mode...</h4>
    <ul>
        <li><b>Timed</b><br>
            <P>In Timed mode, the fields <code>Target</code> and <code>Ping (S)</code> must be populated.</P>
            <p>Target must be a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code></p>
            <p>Ping (S) is the number of seconds between pings</p>
        </li>
        <li><b>Triggered</b><br>
            <p>In Triggered mode, you must connect an input wire and pass a <code>msg</code> in to trigger the ping operation.</p>
            <p>If <code>Target</code> is populated, this will be used as the host/ip. The Target must be is a CSV list of
                hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code></p>

            <p>If Target is left empty, you can pass a CSV string or an array of hosts in <code>msg.payload</code>.
                <ul>
                    <li><b>string</b> - a CSV list of hosts / IPs e.g. <code>"192.168.0.1"</code> or <code>"192.168.0.1, www.google.com"</code> </li>
                    <li><b>array</b> - an array of hosts as strings or objects. <b>Note</b>: The object must contain at minimum <code>.host</code>.
                        Optionally, you can add a <code>timeout</code> property between 1000 & 30000 (default is 5000 / 5 seconds).
                        Additionally, you can add whatever other properties you wish to this object and when the ping result is returned, it will
                        be passed to the next node in <code>msg.ping</code> for use downstream</li>
                    <li>Example array payload input: <pre>[
    "192.168.0.99",
    {
        "host":"192.168.0.1",
        "name":"The router"
    },
    {
        "host":"myapiserver.com",
        "name":"external API",
        "timeout": 20000,
        "support":"support@myapiserver.com"
    }
]</pre>         </li>
                </ul>
            </p>
        </li>
    </ul>
    <p><b>Note</b>: if running inside Ubuntu Snap you will need to manually start the network-observe interface.
        <code>snap connect node-red:network-observe</code>.</p>
</script>
